Plugin Development Guide

Overview

The SuiteQL Query Tool supports a plugin architecture that allows developers to extend functionality without modifying the main script. Plugins can:

• Add custom server-side handlers and hooks
• Inject UI elements at designated points
• Register client-side hooks for various events
• Disable built-in features
• Store persistent settings

Installation

Plugins are JavaScript files that export a plugin definition object. Files must be named with the .sqt-plugin.js extension (or .sqt-plugin.json for JSON-only plugins).

Setup Steps

1. 1 Upload plugin files to a folder in your NetSuite File Cabinet
2. 2 Set CONFIG.PLUGIN_FOLDER_ID in the suitelet to this folder's ID
3. 3 Refresh the SuiteQL Query Tool

Basic Plugin Structure

(function() {
    return {
        // Required fields
        name: 'my-plugin',
        version: '1.0.0',

        // Optional fields
        minAppVersion: '2026.1',
        description: 'My custom plugin',
        author: 'Your Name',
        dependencies: [],
        disables: [],

        // Plugin functionality
        server: { ... },
        client: { ... },
        ui: { ... },
        settings: { ... }
    };
})()

Plugin Definition

Required Fields

Optional Fields

Disableable Features

The following feature names can be used in the disables array:

Server-Side Integration

Hooks

Server hooks are called during query execution on the NetSuite server.

server: {
    hooks: {
        // Called before query execution
        // Can modify the query or cancel execution
        onBeforeQuery: function(data, plugin) {
            // data.query - the SQL to execute
            // data.payload - the request payload
            // data.originalQuery - unmodified query
            return data; // Return modified data or undefined
        },

        // Called after successful query
        onAfterQuery: function(data, plugin) {
            // data.query - executed SQL
            // data.payload - request payload
            // data.response - query results
            return data;
        },

        // Called when query execution fails
        onError: function(data, plugin) {
            // data.query - the SQL that failed
            // data.payload - request payload
            // data.error - the error object
        }
    }
}

Custom Handlers

Add custom server-side endpoints:

server: {
    handlers: {
        myHandler: function(context, payload, modules, plugin) {
            // context - NetSuite context object
            // payload - request payload
            // modules - NetSuite modules (file, https, log, etc.)
            // plugin - this plugin's definition

            context.response.write(JSON.stringify({
                result: 'success'
            }));
        }
    }
}

Client-Side Integration

Hooks

Client hooks are called in the browser.

client: {
    hooks: {
        // Called when app initialization completes
        onInit: function(data) {
            // data.state - app state object
            // data.config - app config
            return data;
        },

        // Called before query execution
        onBeforeQuery: function(data) {
            // data.query - SQL to execute
            // data.options - query options
            // Return { ...data, cancel: true } to cancel
            return data;
        },

        // Called after successful query
        onAfterQuery: function(data) {
            // data.query - executed SQL
            // data.results - query results
            // data.elapsedTime - execution time
            // data.rowCount - number of rows
            return data;
        },

        // Called after results render to DOM
        onResultsDisplay: function(data) {
            // data.data - results data
            // data.viewMode - current view mode
            // data.panel - results panel element
            return data;
        },

        // Called before export
        onBeforeExport: function(data) {
            // data.format - export format
            // data.records - data to export
            // Return { ...data, cancel: true } to cancel
            return data;
        },

        // Called after export
        onAfterExport: function(data) {
            // data.format - export format
            // data.rowCount - rows exported
            return data;
        },

        // Called when editor content changes
        onEditorChange: function(data) {
            // data.content - current editor content
            return data;
        }
    }
}

Initialization Function

The init function runs when the plugin loads and can return a public API:

client: {
    init: function(meta, pluginsApi) {
        // meta - { name, version, description }
        // pluginsApi - plugins object with saveSettings, loadSettings, etc.

        // Return public API (optional)
        return {
            doSomething: function() { ... },
            getStatus: function() { ... }
        };
    }
}

UI Injection

Inject HTML at designated points in the interface:

ui: {
    'toolbar-start': '<button onclick="...">Custom</button>',
    'toolbar-end': '<button onclick="...">Custom</button>',
    'more-dropdown': '<div class="sqt-toolbar-dropdown-item">...</div>',
    'ai-dropdown': '<div class="sqt-toolbar-dropdown-item">...</div>',
    'header-right': '<button class="sqt-btn">...</button>',
    'before-editor': '<div class="alert">Notice</div>',
    'editor-toolbar': '<button class="btn btn-sm">...</button>',
    'nl-bar': '<div>NL bar extension</div>',
    'results-header': '<button>Custom action</button>',
    'results-footer': '<div>Summary info</div>',
    'export-menu': '<button onclick="...">Custom Export</button>',
    'options-panel': '<div class="sqt-options-section">...</div>',
    'sidebar-section': '<div>Custom sidebar content</div>',
    'local-library-actions': '<button>...</button>',
    'status-bar': '<span>Status indicator</span>',
    'modals': '<div class="modal">...</div>'
}

Injection Points

Dynamic Injection Points

Some injection points (results-header, results-footer) are rendered dynamically when results are displayed. For these, inject via the onResultsDisplay hook:

client: {
    hooks: {
        onResultsDisplay: function(data) {
            // Inject into results header
            var header = document.getElementById('sqtPluginResultsHeader');
            if (header) {
                header.innerHTML = '<button onclick="myAction()">Custom</button>';
            }

            // Inject into results footer
            var footer = document.getElementById('sqtPluginResultsFooter');
            if (footer) {
                footer.innerHTML = '<div>Row count: ' + data.data.rowCount + '</div>';
            }

            return data;
        }
    }
}

Settings

Using the Settings API

// Save settings (localStorage only)
SQT.plugins.saveSettings('my-plugin', { enabled: true });

// Load settings
var settings = SQT.plugins.loadSettings('my-plugin');

// Save to server (persists across browsers)
SQT.plugins.saveSettings('my-plugin', settings, true);

Settings Schema

Define a schema for automatic settings UI generation:

settings: {
    schema: {
        enabled: {
            type: 'boolean',
            default: true,
            label: 'Enable Feature',
            description: 'Toggle this feature on/off'
        },
        threshold: {
            type: 'number',
            default: 100,
            label: 'Threshold',
            description: 'Set the threshold value'
        }
    }
}

Best Practices

1. Use unique names: Prefix plugin names with your organization (e.g., acme-audit-logger)
2. Handle errors gracefully: Wrap code in try/catch blocks to prevent breaking the main app
3. Check for dependencies: Use minAppVersion and dependencies to ensure compatibility
4. Clean up: Remove event listeners and timers when appropriate
5. Test thoroughly: Test with and without the plugin enabled
6. Document your plugin: Include clear usage instructions for other developers

Example Plugin

See query-logger.sqt-plugin.js in the sample-plugins folder for a complete example demonstrating:

• Server-side hooks
• Client-side hooks
• UI injection
• Settings management
• Public API exposure

Troubleshooting

Plugin not loading

• Check file naming (must end in .sqt-plugin.js)
• Verify CONFIG.PLUGIN_FOLDER_ID is set correctly
• Check NetSuite execution log for errors

Hooks not firing

• Ensure hook function names are spelled correctly
• Check browser console for JavaScript errors
• Verify plugin registered successfully (check console for "[SQT Plugins] Registered: your-plugin")

UI not appearing

• Check injection point name is correct
• Verify HTML is valid
• Look for CSS conflicts
• For dynamic injection points, ensure you're using the onResultsDisplay hook